---
title: Images
description: Apprenez à utiliser les images dans Astro.
i18nReady: true
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import RecipeLinks from "~/components/RecipeLinks.astro";
import { Steps } from '@astrojs/starlight/components'
import ReadMore from '~/components/ReadMore.astro';

Astro vous propose plusieurs façons d'utiliser des images sur votre site, qu'elles soient stockées localement dans votre projet, liées à une URL externe ou gérées dans un CMS ou un CDN.

Astro fournit des composants Astro intégrés comme [`<Image />`](#image-) et [`<Picture />`](#picture-), le traitement de la [syntaxe d'image Markdown](#images-dans-les-fichiers-markdown) (`![]()`), des [composants SVG](#composants-svg) et [une fonction de génération d'images](#générer-des-images-avec-getimage) pour optimiser et/ou transformer vos images. De plus, vous pouvez configurer [le redimensionnement automatique des images adaptatives](#comportement-des-images-adaptatives) par défaut, ou définir des propriétés adaptatives sur des composants Image et Picture individuels.

Vous pouvez toujours choisir d'utiliser des images et des fichiers SVG en utilisant des éléments HTML natifs dans les fichiers `.astro` ou Markdown, ou la manière standard pour votre type de fichier (par exemple `<img />` dans MDX et JSX). Cependant, Astro n'effectue aucun traitement ni optimisation de ces images.

Il n'y a pas non plus de prise en charge native des vidéos dans Astro, et nous vous recommandons de choisir un [service de vidéos hébergées](/fr/guides/media/) pour gérer les demandes d'optimisation et de diffusion de contenu vidéo.

<ReadMore>Consultez la référence complète de l'API des composants [`<Image />`](/fr/reference/modules/astro-assets/#image-) et [`<Picture />`](/fr/reference/modules/astro-assets/#picture-).</ReadMore>

## Où stocker les images

### `src/` vs `public/`

Nous recommandons que les images locales soient conservées dans `src/` si possible afin qu'Astro puisse les transformer, les optimiser et les regrouper. Les fichiers dans le répertoire `public/` sont toujours servis ou copiés dans le dossier de compilation tels quels, sans aucun traitement.

Vos images locales stockées dans `src/` peuvent être utilisées par tous les fichiers de votre projet : `.astro`, `.md`, `.mdx`, `.mdoc` et d'autres frameworks d'interface utilisateur sous forme d'importations de fichiers. Les images peuvent être stockées dans n'importe quel dossier, y compris avec votre contenu.

Stockez vos images dans le dossier `public/` pour éviter tout traitement. Ces images sont disponibles dans vos fichiers de projet sous forme d'URL sur votre domaine et vous permettent d'avoir un lien public direct vers elles. Par exemple, le favicon de votre site sera généralement placé à la racine de ce dossier où les navigateurs pourront l'identifier.

### Images distantes

Vous pouvez également choisir de stocker vos images à distance, dans un [système de gestion de contenu (CMS)](/fr/guides/cms/) ou une plateforme de [gestion des ressources numériques (DAM)](/fr/guides/media/). Astro peut récupérer vos données à distance à l'aide d'API ou afficher des images à partir de leur chemin d'accès complet.

Pour une protection supplémentaire lors du traitement de sources externes, les composants d'image et la fonction d'assistance d'Astro traiteront uniquement (par exemple, optimiseront, transformeront) les images provenant de [sources d'images autorisées spécifiées dans votre configuration](#autoriser-les-images-distantes). Les images distantes provenant d’autres sources seront affichées sans traitement.

## Images dans les fichiers `.astro`

<p>

**Options :** `<Image />`, `<Picture />`, `<img>`, `<svg>`, composants SVG
</p>

Le langage de création de modèles d'Astro vous permet de générer des images optimisées avec le composant [`<Image />`](/fr/reference/modules/astro-assets/#image-) d'Astro et de générer plusieurs tailles et formats avec le composant [`<Picture />`](/fr/reference/modules/astro-assets/#picture-) d'Astro. Ces deux composants acceptent également [les propriétés d'image adaptatives](#comportement-des-images-adaptatives) pour un redimensionnement en fonction de la taille du conteneur et de la taille et de la résolution de l'écran de l'appareil.

De plus, vous pouvez importer et utiliser des [fichiers SVG comme composants Astro](#composants-svg) dans les composants `.astro`.

Toutes les balises HTML natives, y compris `<img>` et `<svg>`, sont également disponibles dans les composants `.astro`. [Les images affichées avec des balises HTML](#afficher-des-images-non-traitées-avec-la-balise-html-img) ne seront pas traitées (par exemple optimisées, transformées) et seront copiées telles quelles dans votre dossier de compilation.

Pour toutes les images dans les fichiers `.astro`, **la valeur de l'attribut `src` de l'image est déterminée par l'emplacement de votre fichier image** :

- Une image locale dans le dossier `src/` de votre projet utilise une importation à partir du chemin relatif du fichier.
  
  Les composants Image et Picture utilisent directement l'importation nommée (par exemple `src={rocket}`), tandis que la balise `<img>` utilise la propriété d'objet `src` de l'importation (par exemple `src={rocket.src}`).

- Les images distantes et celles présentes dans `public/` utilisent une URL.

  Fournissez une URL complète pour les images distantes (par exemple, `src="https://www.example.com/images/mon-image-distante.jpg"`), ou une URL relative à votre site qui correspond à l'emplacement de votre fichier dans votre dossier `public/` (par exemple, `src="/images/mon-image-publique.jpg"` pour une image située dans `public/images/mon-image-publique.jpg`).

```astro title="src/pages/blog/my-images.astro"
---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="Un oiseau assis sur un nid d'œufs." />
<Image src="/images/bird-in-public-folder.jpg" alt="Un oiseau." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="Un oiseau." width="50" height="50" />

<img src={localBirdImage.src} alt="Un oiseau assis sur un nid d'œufs.">
<img src="/images/bird-in-public-folder.jpg" alt="Un oiseau.">
<img src="https://example.com/remote-bird.jpg" alt="Un oiseau.">
```

<ReadMore>Consultez la référence complète de l'API des composants [`<Image />`](/fr/reference/modules/astro-assets/#image-) et [`<Picture />`](/fr/reference/modules/astro-assets/#picture-), y compris les propriétés obligatoires et facultatives.</ReadMore>

<RecipeLinks slugs={["fr/recipes/dynamically-importing-images" ]}/>


## Images dans les fichiers Markdown

<p>

**Options :** `![]()`, `<img>` (avec des images publiques ou distantes)
</p>

Utilisez la syntaxe Markdown standard `![alt](src)` dans vos fichiers `.md`. Vos images locales stockées dans `src/` et les images distantes seront traitées et optimisées. Lorsque vous [configurez des images adaptatives globalement](/fr/reference/configuration-reference/#imagelayout), ces images seront également [adaptatives](#comportement-des-images-adaptatives).

Les images placées dans le dossier `public/` ne sont jamais optimisées.

```md
<!-- src/pages/post-1.md -->

# Ma page Markdown

<!-- Image locale placée dans src/assets/ -->
<!-- Utiliser un chemin de fichier relatif ou un alias d'importation -->
![Un ciel étoilé.](../assets/stars.png)

<!-- Image placée dans public/images/ -->
<!-- Utiliser le chemin du fichier relatif à public/ -->
![Un ciel étoilé.](/images/stars.png)

<!-- Image distante sur un autre serveur -->
<!-- Utiliser l'URL complète de l'image -->
![Astro](https://example.com/images/image-distante.png)
```

La balise HTML `<img>` peut également être utilisée pour afficher des images placées dans `public/` ou des images distantes sans aucune optimisation ou traitement d'image. Cependant, `<img>` n'est pas prise en charge pour vos images locales dans `src`.

Les composants `<Image />` et `<Picture />` ne sont pas disponibles dans les fichiers `.md`. Si vous avez besoin de plus de contrôle sur les attributs de votre image, nous vous recommandons d'utiliser [l'intégration MDX d'Astro](/fr/guides/integrations-guide/mdx/) pour ajouter la prise en charge du format de fichier `.mdx`. MDX offre des [options d'image supplémentaires disponibles dans MDX](#images-dans-les-fichiers-mdx), notamment la combinaison de composants avec la syntaxe Markdown.

## Images dans les fichiers MDX

<p>

**Options :** `<Image />`, `<Picture />`, `<img />`, `![]()`, composants SVG
</p>

Vous pouvez utiliser les composants `<Image />` et `<Picture />` d'Astro dans vos fichiers `.mdx` en important à la fois le composant et votre image. Utilisez-les tels qu'ils sont [utilisés dans les fichiers `.astro`](#images-dans-les-fichiers-astro). La balise JSX `<img />` est également prise en charge pour les images non traitées et [utilise la même importation d'image que la balise HTML `<img>`](#afficher-des-images-non-traitées-avec-la-balise-html-img).

De plus, il existe une prise en charge de la [syntaxe Markdown standard `![alt](src)`](#images-dans-les-fichiers-markdown) sans importation requise.

```mdx title="src/pages/post-1.mdx"
---
title: Le titre de ma page
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# Ma page MDX

// Image locale placée dans le même dossier
![Houston dans la nature](houston.png)

// Image locale placée dans src/assets/
<Image src={rocket} alt="Une fusée dans l'espace." />
<img src={rocket.src} alt="Une fusée dans l'espace." />
![Une fusée dans l'espace](../assets/rocket.png)

// Image placée dans public/images/
<Image src="/images/stars.png" alt="Un ciel étoilé." />
<img src="/images/stars.png" alt="Un ciel étoilé." />
![Un ciel étoilé.](/images/stars.png)

// Image distante sur un autre serveur
<Image src="https://example.com/images/image-distante.png" />
<img src="https://example.com/images/image-distante.png" />
![Astro](https://example.com/images/image-distante.png)

```

<ReadMore>Consultez la référence complète de l'API pour les composants [`<Image />`](/fr/reference/modules/astro-assets/#image-) et [`<Picture />`](/fr/reference/modules/astro-assets/#picture-).</ReadMore>

## Images dans les composants de framework UI

<p>

**Options d'image :** la syntaxe d'image propre au framework (par exemple `<img />` dans JSX, `<img>` dans Svelte)
</p>

[Les images locales doivent d'abord être importées](#afficher-des-images-non-traitées-avec-la-balise-html-img) pour accéder à leurs propriétés d'image telles que `src`. Ensuite, elles peuvent être rendues comme vous le feriez normalement dans la syntaxe d'image propre à ce framework :

```jsx title="src/components/ReactImage.jsx"
import stars from "../assets/stars.png";

export default function ReactImage() {
  return (
    <img src={stars.src} alt="Un ciel étoilé." />
  )
}
```

```svelte title="src/components/SvelteImage.svelte"
<script>
  import stars from '../assets/stars.png';
</script>

<img src={stars.src} alt="Un ciel étoilé." />

```

Les composants Astro (par exemple `<Image />`, `<Picture />`, composants SVG) ne sont pas disponibles dans les composants de framework UI car [un îlot de client doit contenir uniquement du code valide pour son propre framework](/fr/guides/framework-components/#puis-je-utiliser-les-composants-astro-à-lintérieur-des-composants-de-mon-framework-).

Mais vous pouvez transmettre le contenu statique généré par ces composants à un composant de framework dans un fichier `.astro` [en tant qu'enfants](/fr/guides/framework-components/#passer-des-enfants-à-des-composants-de-framework) ou en utilisant un [`<slot/>` nommé](/fr/guides/framework-components/#puis-je-utiliser-les-composants-astro-à-lintérieur-des-composants-de-mon-framework-) :


```astro title="src/components/ImageWrapper.astro"
---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---

<ReactComponent>
  <Image src={stars} alt="Un ciel étoilé." />
</ReactComponent>
```

## Composants Astro pour les images

Astro fournit deux composants Astro intégrés pour les images (`<Image />` et `<Picture />`) et vous permet également d'importer des fichiers SVG et de les utiliser comme composants Astro. Ces composants peuvent être utilisés dans tous les fichiers pouvant importer et restituer des composants `.astro`.

### `<Image />`

Utilisez le composant Astro intégré `<Image />` pour afficher des versions optimisées :

- de vos images locales situées dans le dossier `src/`
- d'[images distantes configurées](#autoriser-les-images-distantes) provenant de sources autorisées

`<Image />` peut transformer les dimensions, le type de fichier et la qualité d'une image locale ou distante autorisée pour contrôler l'image affichée. Cette transformation s'effectue lors de la création des pages pré-rendues. Si votre page est rendue à la demande, elle s'effectue à la volée lors de son affichage. La balise `<img>` résultante inclut les attributs `alt`, `loading` et `decoding` et déduit les dimensions de l'image pour éviter le décalage cumulatif de mise en page (« Cumulative Layout Shift » en anglais ou CLS).

:::note[Qu'est-ce que le décalage cumulatif de la mise en page ?]
[Cumulative Layout Shift (CLS)](https://web.dev/cls/) est une mesure de Core Web Vital qui permet d'évaluer le décalage du contenu de votre page pendant le chargement. Le composant `<Image />` optimise le CLS en définissant automatiquement la bonne largeur (`width`) et la bonne hauteur (`height`) pour vos images locales.
:::

```astro title="src/components/MyComponent.astro"
---
// importer le composant Image et l'image
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image est en 1600x900
---

<!-- `alt` est obligatoire pour le composant Image -->
<Image src={myImage} alt="La description de mon image." />
```

```html
<!-- Résultat du pré-rendu -->
<!-- L'image est optimisée, les attributs appropriés sont appliqués -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="La description de mon image."
/>

<!-- Résultat du rendu à la demande -->
<!-- src utilisera un point de terminaison généré à la demande -->
<img
  src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
  <!-- ... -->
/>
```

Le composant `<Image />` accepte [plusieurs propriétés de composant](/fr/reference/modules/astro-assets/#propriétés-dimage) ainsi que tous les attributs acceptés par la balise HTML `<img>`.

L'exemple suivant fournit une classe (`class`) au composant Image qui s'appliquera à l'élément final `<img>`.

```astro title="src/pages/index.astro" 'class="my-class"'
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---

<!-- `alt` est obligatoire pour le composant Image -->
<Image src={myImage} alt="" class="my-class" />
```

```html 'class="my-class"'
<!-- Résultat du pré-rendu -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="my-class"
  alt=""
/>

```

:::tip
Vous pouvez également utiliser le composant `<Image />` pour les images du dossier `public/` ou les images distantes non spécifiquement configurées dans votre projet, même si ces images ne seront ni optimisées ni traitées. L'image résultante sera la même que celle obtenue en utilisant la balise HTML `<img>`.

Cependant, l'utilisation du composant Image pour toutes les images offre une expérience de création cohérente et empêche le décalage de mise en page cumulé (CLS), même pour vos images non optimisées.
:::

### `<Picture />`

<p><Since v="3.3.0" /></p>

Utilisez le composant Astro intégré `<Picture />` pour générer une balise `<picture>` avec plusieurs formats et/ou tailles d'images. Cela vous permet de spécifier les formats de fichiers préférés à afficher et en même temps, de fournir un format de repli. Comme le composant [`<Image />`](#image-), les images seront traitées au moment de la compilation pour les pages pré-rendues. Lorsque votre page est rendue à la demande, le traitement se produira à la volée lorsque la page sera consultée.

L'exemple suivant utilise le composant `<Picture />` pour transformer un fichier `.png` local en un format `avif` et `webp` convivial pour le web ainsi que l'image au format `.png` avec la balise `<img>` qui peut être affichée comme solution de repli si nécessaire :

```astro title="src/pages/index.astro"
---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image est de 1600x900
---

<!-- `alt` est obligatoire pour le composant Image -->
<Picture src={myImage} formats={['avif', 'webp']} alt="Une description de mon image." />
```

```html
<!-- Résultat du pré-rendu -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Une description de mon image."
  />
</picture>
```

<ReadMore>Consultez le détail des [propriétés du composant `<Picture />`](/fr/reference/modules/astro-assets/#propriétés-de-picture) dans la référence `astro:assets`.</ReadMore>

### Comportement des images adaptatives

 <p><Since v="5.10.0" /></p>

Les images adaptatives sont des images qui s'ajustent pour améliorer les performances sur différents appareils. Ces images peuvent être redimensionnées pour s'adapter à leur conteneur et peuvent être diffusées dans différentes tailles en fonction de la taille et de la résolution de l'écran de votre visiteur.

Avec les [propriétés d'image adaptatives](/fr/reference/modules/astro-assets/#propriétés-des-images-adaptatives) appliquées aux composants `<Image />` ou `<Picture />`, Astro générera automatiquement les valeurs `srcset` et `sizes` requises pour vos images, et appliquera les [styles nécessaires pour garantir qu'elles se redimensionnent correctement](#styles-des-images-adaptatives).

Lorsque ce comportement adaptatif est [configuré globalement à l'aide d'`image.layout`](/fr/reference/configuration-reference/#imagelayout), il s'appliquera à tous les composants d'image ainsi qu'à toutes les images locales et distantes utilisant [la syntaxe Markdown `![]()`](/fr/guides/images/#images-dans-les-fichiers-markdown).

Les images de votre dossier `public/` ne sont jamais optimisées et les images adaptatives ne sont pas prises en charge.

:::note
Une seule image adaptative générera plusieurs images de différentes tailles afin que le navigateur puisse afficher la meilleure à votre visiteur.

Pour les pages pré-rendues, cela se produit pendant la compilation et peut augmenter le temps de compilation de votre projet, surtout si vous avez un grand nombre d'images.

Pour les pages rendues à la demande, les images sont générées au fur et à mesure des visites. Cela n'a aucun impact sur les délais de création, mais peut augmenter le nombre de transformations d'image effectuées lors de l'affichage. Selon votre service d'images, cela peut entraîner des frais supplémentaires.
:::

<ReadMore>En savoir plus sur [les images adaptatives dans la documentation de MDN](https://developer.mozilla.org/fr/docs/Web/HTML/Guides/Responsive_images).</ReadMore>

#### Sortie HTML générée pour les images adaptatives

Lorsqu'une mise en page est définie, soit par défaut, soit sur un composant individuel, les attributs `srcset` et `sizes` des images sont automatiquement générés en fonction de leurs dimensions et de leur type de mise en page. Les images avec des mises en page `constrained` et `full-width` se verront appliquer des styles pour garantir leur redimensionnement en fonction de leur conteneur.

```astro title="src/components/MyComponent.astro"
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="Une description de mon image." layout='constrained' width={800} height={600} />
```

Ce composant `<Image />` générera la sortie HTML suivante sur une page pré-rendue :

```html
<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="Une description de mon image"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>
```

#### Styles des images adaptatives

Définir [`image.responsiveStyles: true`](/fr/reference/configuration-reference/#imageresponsivestyles) applique un petit nombre de styles globaux pour garantir le bon redimensionnement de vos images. Dans la plupart des cas, il est préférable de les activer par défaut ; vos images ne seront pas adaptatives sans styles supplémentaires.

Cependant, si vous préférez gérer vous-même le style des images adaptatives ou si vous devez [remplacer ces valeurs par défaut lors de l'utilisation de Tailwind 4](#images-adaptatives-avec-tailwind-4), laissez la valeur `false` configurée par défaut.

Les styles globaux appliqués par Astro dépendent du type de mise en page et sont conçus pour produire le meilleur résultat pour les attributs `srcset` et `sizes` générés. Voici les styles par défaut :

```css title="Styles des images adaptatives"
:where([data-astro-image]) {
	object-fit: var(--fit);
	object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
	width: 100%;
}
:where([data-astro-image='constrained']) {
	max-width: 100%;
}
```

Les styles utilisent la pseudo-classe [`:where()`](https://developer.mozilla.org/fr/docs/Web/CSS/:where), qui a une [spécificité](https://developer.mozilla.org/fr/docs/Web/CSS/CSS_cascade/Specificity) de 0, ce qui signifie qu'il est facile de la remplacer par vos propres styles. Tout sélecteur CSS aura une spécificité supérieure à `:where()` ; vous pouvez donc facilement remplacer les styles en ajoutant vos propres styles pour cibler l'image.

Vous pouvez remplacer les styles `object-fit` et `object-position` image par image en définissant les props `fit` et `position` sur le composant `<Image />` ou `<Picture />`.

#### Images adaptatives avec Tailwind 4

Tailwind 4 est compatible avec les styles adaptatifs par défaut d'Astro. Cependant, Tailwind utilise des [couches en cascade](https://developer.mozilla.org/fr/docs/Web/CSS/@layer), ce qui signifie que ses règles ont toujours une spécificité inférieure à celle des règles qui n'utilisent pas de couches, y compris les styles adaptatifs d'Astro. Par conséquent, les styles d'Astro auront la priorité sur les styles de Tailwind. Pour utiliser les règles Tailwind au lieu des styles par défaut d'Astro, n'activez pas les [styles adaptatifs par défaut d'Astro](/fr/reference/configuration-reference/#imageresponsivestyles).


## Composants SVG
<p><Since v="5.7.0" /></p>

Astro vous permet d'importer des fichiers SVG et de les utiliser comme composants Astro. Astro intègre le contenu SVG dans votre sortie HTML.

Référencez l'importation par défaut de tout fichier `.svg` local. Cette importation étant traitée comme un composant Astro, vous devez utiliser les mêmes conventions (par exemple, la casse) que pour l'[utilisation de balises dynamiques](/fr/reference/astro-syntax/#balises-dynamiques).

```astro title="src/components/MonComposantAstro.astro"
---
import Logo from './chemin/vers/un/fichier.svg';
---

<Logo />
```

Votre composant SVG, comme `<Image />` ou tout autre composant Astro, n'est pas disponible dans les composants de framework UI, mais peut [être transmis à un composant du framework](#images-dans-les-composants-de-framework-ui) dans un composant `.astro`.

#### Attributs des composants SVG

Vous pouvez transmettre des props tels que `width`, `height`, `fill`, `stroke` et tout autre attribut accepté par l'[élément natif `<svg>`](https://developer.mozilla.org/fr/docs/Web/SVG/Reference/Element/svg). Ces attributs seront automatiquement appliqués à l'élément `<svg>` sous-jacent. Si une propriété est présente dans le fichier `.svg` d'origine et transmise au composant, la valeur transmise au composant remplacera la valeur d'origine.


```astro title="src/components/MonComposantAstro.astro"
---
import Logo from '../assets/logo.svg';
---

<Logo width={64} height={64} fill="currentColor" />
```

#### Type `SvgComponent`

<Since v="5.14.0" />

Vous pouvez également appliquer la sûreté du typage pour vos ressources `.svg` à l'aide du type `SvgComponent` :

```astro title="src/components/Logo.astro"
---
import type { SvgComponent } from "astro/types";
import HomeIcon from './Home.svg'

interface Link {
	url: string
	text: string
	icon: SvgComponent
}

const links: Link[] = [
	{
		url: '/',
		text: 'Accueil',
		icon: HomeIcon
	}
]
---
```

### Création de composants d'image personnalisés

Vous pouvez créer un composant d'image personnalisé et réutilisable en enveloppant le composant `<Image />` ou `<Picture/>` dans un autre composant Astro. Cela vous permet de définir les attributs et les styles par défaut une seule fois.

Par exemple, vous pouvez créer un composant pour les images de vos articles de blog qui reçoit des attributs comme props et applique des styles cohérents à chaque image :

```astro title="src/components/BlogPostImage.astro"
---
import { Image } from 'astro:assets';

const { src, ...attrs } = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>
```

## Afficher des images non traitées avec la balise HTML `<img>`

La [syntaxe de modèle Astro](/fr/reference/astro-syntax/) prend également en charge l'écriture directe d'une balise `<img>`, avec un contrôle total sur sa sortie finale. Ces images ne seront ni traitées ni optimisées. Elle accepte toutes les propriétés de la balise HTML `<img>`, la seule propriété obligatoire étant `src`. Cependant, il est fortement recommandé d'inclure [la propriété `alt` pour l'accessibilité](#texte-alternatif).

### Images dans `src/`

Les images locales doivent être importées à partir du chemin relatif du fichier `.astro` existant, ou vous pouvez configurer et utiliser un [alias d'importation](/fr/guides/imports/#alias). Vous pouvez ensuite accéder à la source de l'image et aux autres propriétés à utiliser dans la balise `<img>`.

Les ressources d'image importées correspondent à la signature suivante :

```ts
interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}
```

L'exemple suivant utilise les propriétés « height » et « width » de l'image pour éviter le décalage de mise en page cumulé (CLS) et améliorer les Core Web Vitals :

```astro title="src/pages/posts/post-1.astro" "myDog.width" "myDog.height"
---
// importer des images locales
import myDog from '../../images/pets/local-dog.jpg';
---
// accéder aux propriétés de l'image
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="Un chien qui aboie." />
```

### Images dans `public/`
Pour les images situées dans « public/ », utilisez le chemin d'accès au fichier de l'image par rapport au dossier public comme valeur pour `src` :

```astro '"/images/public-cat.jpg"'
<img src="/images/public-cat.jpg" alt="Un chat endormi." >
```

### Images distantes

Pour les images distantes, utilisez l'URL complète de l'image comme valeur pour `src` :

```astro '"https://example.com/remote-cat.jpg"'
<img src="https://example.com/remote-cat.jpg" alt="Un chat endormi." >
```

### Choisir entre `<Image />` et `<img>`

Le composant `<Image />` optimise votre image et déduit la largeur et la hauteur (pour les images qu'il peut traiter) en fonction du rapport hauteur/largeur d'origine pour éviter le CLS. C'est la méthode privilégiée pour utiliser les images dans les fichiers `.astro` chaque fois que cela est possible.

Utilisez l'élément HTML `<img>` lorsque vous ne pouvez pas utiliser le composant `<Image />`, par exemple :
  - pour les formats d'image non pris en charge
  - lorsque vous ne souhaitez pas que votre image soit optimisée par Astro
  - pour accéder à et modifier l'attribut `src` de manière dynamique côté client


## Utilisation d'images provenant d'un CMS ou d'un CDN

Les CDN d'images fonctionnent avec [toutes les options d'images d'Astro](#images-dans-les-fichiers-astro). Utilisez l'URL complète d'une image comme attribut `src` dans le composant `<Image />`, une balise `<img>`, ou dans la notation Markdown. Pour l'optimisation des images distantes, il faut également [configurer les domaines autorisés ou les modèles d'URL](#autoriser-les-images-distantes).

Alternativement, le CDN peut fournir ses propres SDK pour s'intégrer plus facilement dans un projet Astro. Par exemple, Cloudinary prend en charge un [SDK Astro](https://astro.cloudinary.dev/) qui vous permet d'insérer facilement des images avec leur composant `CldImage` ou un [SDK Node.js](https://cloudinary.com/documentation/node_integration) qui peut générer des URL à utiliser avec une balise `<img>` dans un environnement Node.js.

<ReadMore>Consultez la référence complète de l'API des composants [`<Image />`](/fr/reference/modules/astro-assets/#image-) et [`<Picture />`](/fr/reference/modules/astro-assets/#picture-).</ReadMore>

## Autoriser les images distantes

Vous pouvez configurer des listes de domaines et de modèles d'URL autorisés en tant que source d'image pour l'optimisation des images à l'aide de [`image.domains`](/fr/reference/configuration-reference/#imagedomains) et [`image.remotePatterns`](/fr/reference/configuration-reference/#imageremotepatterns). Cette configuration est une couche de sécurité supplémentaire pour protéger votre site lors de l'affichage d'images provenant d'une source externe.

Les images distantes provenant d'autres sources ne seront pas optimisées, mais l'utilisation du composant `<Image />` pour ces images empêchera le décalage de mise en page cumulatif (CLS).

Par exemple, la configuration suivante permettra uniquement l'optimisation des images distantes provenant de `astro.build` :

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});
```

La configuration suivante autorisera uniquement les images distantes provenant d'hôtes HTTPS :

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});
```

## Images dans les collections de contenu

Vous pouvez déclarer une image associée à une entrée de collection de contenu, telle que l'image de couverture d'un article de blog, dans votre frontmatter en utilisant son chemin relatif au dossier actuel :

```md title="src/content/blog/my-post.md" {3}
---
title: "Mon premier article de blog"
cover: "./firstpostcover.jpeg" # se résoudra en "src/content/blog/firstblogcover.jpeg"
coverAlt: "Photographie d'un coucher de soleil derrière une chaîne de montagnes."
---

Ceci est un article de blog
```

L'assistant `image` pour le schéma des collections de contenu vous permet de valider et d'importer l'image.

```ts title="src/content.config.ts"
import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
	schema: ({ image }) => z.object({
		title: z.string(),
		cover: image(),
		coverAlt: z.string(),
	}),
});

export const collections = {
	blog: blogCollection,
};
```

L'image sera importée et transformée en métadonnées, vous permettant de la transmettre comme `src` à `<Image/>`, `<img>`, ou `getImage()` dans un composant Astro.

L'exemple ci-dessous montre une page d'index de blog qui affiche la photo de couverture et le titre de chaque article de blog en utilisant le schéma précédent :

```astro title="src/pages/blog.astro" {10}
---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---

{
	allBlogPosts.map((post) => (
		<div>
			<Image src={post.data.cover} alt={post.data.coverAlt} />
			<h2>
				<a href={"/blog/" + post.slug}>{post.data.title}</a>
			</h2>
		</div>
	))
}
```

## Générer des images avec `getImage()`

La fonction `getImage()` est prévue pour générer des images destinées à être utilisées ailleurs que directement en HTML, par exemple dans une [route d'API](/fr/guides/endpoints/#points-de-terminaison-du-serveur-routes-api). Lorsque vous avez besoin d'options que les composants `<Picture>` et `<Image>` ne prennent pas actuellement en charge, vous pouvez utiliser la fonction `getImage()` pour créer votre propre composant `<Image />` personnalisé.

<ReadMore>Pour en savoir plus, consultez la [référence `getImage()`](/fr/reference/modules/astro-assets/#getimage).</ReadMore>

<RecipeLinks slugs={["fr/recipes/build-custom-img-component" ]}/>

## Texte alternatif

Tous les utilisateurs ne voient pas les images de la même manière. L'accessibilité est donc une préoccupation particulièrement importante lors de l'utilisation d'images. Utilisez l'attribut `alt` pour fournir un [texte alternatif descriptif](https://www.w3.org/WAI/tutorials/images/) pour les images.

Cet attribut est requis pour les composants `<Image />` et `<Picture />`. Si aucun texte alt n'est fourni, un message d'erreur utile vous rappellera d'inclure l'attribut `alt`.

Si l'image est simplement décorative (c'est-à-dire qu'elle ne contribue pas à la compréhension de la page), définissez `alt=""` pour que les lecteurs d'écran sachent qu'ils doivent ignorer l'image.

## Service d'images par défaut

[Sharp](https://github.com/lovell/sharp) est le service d'images par défaut utilisé pour `astro:assets`. Vous pouvez configurer le service d'images en utilisant l'option [`image.service`](/fr/reference/configuration-reference/#imageservice).

:::note
Lorsque vous utilisez un [gestionnaire de paquets strict](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) comme `pnpm`, vous pouvez avoir besoin d'installer manuellement Sharp dans votre projet même si c'est une dépendance d'Astro :

```bash
pnpm add sharp
```
:::

### Configurer le service no-op passthrough

Si votre [adaptateur](https://astro.build/integrations/?search=&categories%5B%5D=adapters) ne prend pas en charge l'optimisation d'image Sharp intégrée à Astro (par exemple Deno, Cloudflare), vous pouvez configurer un service d'image sans opération (ou « no-op » en anglais) pour vous permettre d'utiliser les composants `<Image />` et `<Picture />`. Notez qu'Astro n'effectue aucune transformation ou traitement d'image dans ces environnements. Cependant, vous pouvez toujours profiter des autres avantages de l'utilisation de `astro:assets`, y compris l'absence de décalage cumulatif de la mise en page (CLS), l'application de l'attribut `alt`, et une expérience de création cohérente.

Configurez `passthroughImageService()` pour éviter les traitements d'image Sharp :

```js title="astro.config.mjs" ins={4-6} "passthroughImageService"
import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});
```

## Mise en cache des ressources

Astro stocke les images traitées dans un répertoire cache lors de la création du site, tant pour les images locales que pour les [images distantes provenant de sources autorisées](#autoriser-les-images-distantes). En préservant le répertoire de cache entre les compilations, les ressources traitées sont réutilisées, ce qui améliore le temps de compilation et l'utilisation de la bande passante.

Le répertoire de cache par défaut est `./node_modules/.astro`, mais il peut être modifié en utilisant le paramètre de configuration [`cacheDir`](/fr/reference/configuration-reference/#cachedir).

### Images distantes

Les images distantes dans le cache des ressources sont gérées en fonction de la [mise en cache HTTP](https://developer.mozilla.org/fr/docs/Web/HTTP/Caching), et respectent l'[en-tête Cache-Control](https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Cache-Control) renvoyé par le serveur distant.
Les images sont mises en cache si l'en-tête Cache-Control le permet et seront utilisées jusqu'à ce qu'elles ne soient plus [fraîches](https://developer.mozilla.org/fr/docs/Web/HTTP/Caching#fra%C3%AEcheur_freshness).

#### Revalidation

<p><Since v="5.1.0" /></p>

La [revalidation](https://developer.mozilla.org/fr/docs/Web/HTTP/Caching#validation_de_cache) réduit l'utilisation de la bande passante et le temps de compilation en vérifiant auprès du serveur distant si une image mise en cache qui a expiré est toujours d'actualité. Si le serveur indique que l'image est encore fraîche, la version mise en cache est réutilisée, sinon l'image est téléchargée à nouveau.

La revalidation nécessite que le serveur distant envoie des en-têtes [Last-Modified](https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Last-Modified) et/ou [Etag (étiquette d'entité)](https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/ETag) avec ses réponses. Cette fonction est disponible pour les serveurs distants qui prennent en charge les en-têtes [If-Modified-Since](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since) et [If-None-Match](https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/If-None-Match).

## Intégrations communautaires

Il existe plusieurs [intégrations d'images communautaires](https://astro.build/integrations?search=images) pour optimiser et travailler avec des images dans votre projet Astro.
